knitr::opts_chunk$set(cache=TRUE)

1 Preamble

1.1 Dependencies

library(Rarr)
library(EBImage)
library(ggplot2)
library(jsonlite)
library(SpatialData)
library(SingleCellExperiment)

# utility for image plotting with 'EBImage'
.plot <- \(i) {
    c <- ifelse(
        length(dim(i)) == 3, 
        "Color", "Grayscale")
    j <- as.array(aperm(i))
    plot(Image(j/max(j), dim(j), c))
}

1.2 Introduction

2 `SpatialData`

The SpatialData class contains 5 elements that are represented as follows:

images: list of ImageArrays
labels: list of LabelArrays
shapes: list of ShapeFrames
points: list of Arrow Datasets
table: a SingleCellExperiment

path <- system.file("extdata", "blobs", package="SpatialData", mustWork=TRUE)
(spd <- readSpatialData(path))

## class: SpatialData
## images(1): blobs_image 
## labels(1): blobs_labels 
## shapes(1): blobs_shapes 
## points(1): blobs_points 
## table: 3 26

2.1 Accession

The following accessors are currently supported:

image/label/shape/pointNames to retrieve available entities of the respective element.
images/labels/shapes/points to retrieve a list of entities of the respective element.
image/label/shape/point to retrieve a single entity of the respective element.
$ to directly access the entities of the respective element.

SpatialData objects behave like a list, i.e., entities of a all elements can be accessed in various (equivalent) ways:

# these are all equivalent
i <- "blobs_image"
element(spd, "images", i)
images(spd)[[i]]
image(spd, i)
spd$images[[i]]

3 `ZarrArray`

The ZarrArray class is essentially an Annotated array-like object, that may contain a dense array or any type of Array (e.g., Sparse/DelayedArray). Derived here-from are the ImageArray and LabelArray classes that represent single entities of images and labels, respectively. These differ slightly in their associated metadata and array properties, but share many functions.

# construction
zarr <- file.path(path, "images", "blobs_image")
(ia <- readArray(zarr))

## class: ImageArray
## channels: 0 1 2 
## axiis(cyx): 3 512 512 
## |-time(0):  
## |-space(2): y x 
## |-channel(1): c

4 Transformations

Only translation, scaling, and rotation of Image/LabelArrays are currently supported via the following functions, each of which expects a object (SD), as well as transformation data t according to:

rotateArray: scalar integer (angle).
scaleArray: numeric vector with as many elements as SD has dimensions.
translateArray: integer vector of length 2 (row/y and col/x translation).

(i <- image(spd))

## class: ImageArray
## channels: 0 1 2 
## axiis(cyx): 3 512 512 
## |-time(0):  
## |-space(2): y x 
## |-channel(1): c

# view available channels
channels(i)

## [1] "0" "1" "2"

Available coordinate systems can be retrieved via coords():

type: type of transformation (one of identity, rotate, scale, …)
data: transformation data (NA when type = "identity")
output.name the target coordinate system’s identity

coords(i)

## DataFrame with 1 row and 6 columns
##    input.name output.name                             input.axes
##   <character> <character>                                 <list>
## 1         cyx      global c:channel:NA,y:space:unit,x:space:unit
##                              output.axes        type   data
##                                   <list> <character> <list>
## 1 c:channel:NA,y:space:unit,x:space:unit    identity     NA

4.1 scale

j <- scaleArray(i, c(1,1,2))
par(mfrow=c(1,2)); .plot(i); .plot(j)

4.2 rotate

j <- rotateArray(i, 30)
par(mfrow=c(1,2)); .plot(i); .plot(j)

5 Visualization

plotSD currently supports overlaying up to 3 elements (an image, label and shape, but not points yet). Argument coord specifies the target coordinate system, and will default the first available shared one if left unspecified. Elements are internally aligned via alignElements, which in turn calls transformArray on the input image and label (type Image/LabelArray). Depending on the underlying metadata, transformArray uses scale/rotate/translateArray for transformation.

path <- system.file("extdata", "raccoon", package="SpatialData", mustWork=TRUE)
(spd <- readSpatialData(path))

## class: SpatialData
## images(1): raccoon 
## labels(1): segmentation 
## shapes(1): circles 
## points(0): 
## table:

plotSD(spd,
    image="raccoon",
    label="segmentation",
    shape="circles",
    alpha.label=1/3,
    alpha.shape=1,
    color.shape="lightgrey")

(img <- image(spd))

## class: ImageArray
## channels: 0 1 2 
## axiis(cyx): 3 768 1024 
## |-time(0):  
## |-space(2): y x 
## |-channel(1): c

(lab <- label(spd))

## class: LabelArray
## axiis(yx): 768 1024 
## |-time(0):  
## |-space(2): y x 
## |-channel(0):

par(mfrow=c(1,2))
.plot(img)
.plot(lab)

6 Query

aggregateImage computed aggregated measurement values from image according to label using fun to summarized measurements (default mean). By default, the first available image and label are used. In the output SingleCellExperiment, rows correspond to channels and columns to unique labels (excluding 0); aggregated xy-coordinates are included in the colData.

(sce <- aggregateImage(spd))

## class: SingleCellExperiment 
## dim: 3 70 
## metadata(0):
## assays(1): ''
## rownames(3): 0 1 2
## rowData names(0):
## colnames(70): 2 3 ... 70 71
## colData names(2): x y
## reducedDimNames(0):
## mainExpName: NULL
## altExpNames(0):

7 Appendix

7.1 Session info

sessionInfo()

## R version 4.3.0 (2023-04-21)
## Platform: aarch64-apple-darwin20 (64-bit)
## Running under: macOS Ventura 13.2.1
## 
## Matrix products: default
## BLAS:   /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/lib/libRblas.0.dylib 
## LAPACK: /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.11.0
## 
## locale:
## [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## time zone: Europe/Zurich
## tzcode source: internal
## 
## attached base packages:
## [1] stats4   stats    graphics utils    methods  base    
## 
## other attached packages:
##  [1] SingleCellExperiment_1.22.0 SummarizedExperiment_1.30.0
##  [3] Biobase_2.60.0              GenomicRanges_1.52.0       
##  [5] GenomeInfoDb_1.36.0         IRanges_2.34.0             
##  [7] S4Vectors_0.38.0            BiocGenerics_0.46.0        
##  [9] MatrixGenerics_1.12.0       matrixStats_0.63.0         
## [11] SpatialData_0.99.0          jsonlite_1.8.4             
## [13] ggplot2_3.4.2               EBImage_4.42.0             
## [15] Rarr_1.0.0                  BiocStyle_2.28.0           
## 
## loaded via a namespace (and not attached):
##  [1] tidyselect_1.2.0        viridisLite_0.4.1       farver_2.1.1           
##  [4] dplyr_1.1.2             filelock_1.0.2          arrow_11.0.0.3         
##  [7] R.utils_2.12.2          bitops_1.0-7            fastmap_1.1.1          
## [10] RCurl_1.98-1.12         digest_0.6.31           lifecycle_1.0.3        
## [13] paws.storage_0.2.0      magrittr_2.0.3          compiler_4.3.0         
## [16] rlang_1.1.1             sass_0.4.5              tools_4.3.0            
## [19] utf8_1.2.3              yaml_2.3.7              knitr_1.42             
## [22] labeling_0.4.2          S4Arrays_1.0.0          htmlwidgets_1.6.2      
## [25] bit_4.0.5               curl_5.0.0              here_1.0.1             
## [28] reticulate_1.28         DelayedArray_0.25.0     abind_1.4-5            
## [31] zellkonverter_1.10.0    withr_2.5.0             purrr_1.0.1            
## [34] R.oo_1.25.0             grid_4.3.0              fansi_1.0.4            
## [37] grDevices_4.3.0         colorspace_2.1-0        scales_1.2.1           
## [40] cli_3.6.1               rmarkdown_2.21          crayon_1.5.2           
## [43] generics_0.1.3          rstudioapi_0.14         httr_1.4.5             
## [46] cachem_1.0.7            stringr_1.5.0           zlibbioc_1.46.0        
## [49] datasets_4.3.0          parallel_4.3.0          assertthat_0.2.1       
## [52] BiocManager_1.30.20     XVector_0.40.0          tiff_0.1-11            
## [55] basilisk_1.12.0         vctrs_0.6.2             Matrix_1.5-4           
## [58] dir.expiry_1.8.0        bookdown_0.33           fftwtools_0.9-11       
## [61] bit64_4.0.5             magick_2.7.4            jpeg_0.1-10            
## [64] locfit_1.5-9.7          jquerylib_0.1.4         glue_1.6.2             
## [67] codetools_0.2-19        stringi_1.7.12          gtable_0.3.3           
## [70] munsell_0.5.0           tibble_3.2.1            pillar_1.9.0           
## [73] basilisk.utils_1.12.0   htmltools_0.5.5         GenomeInfoDbData_1.2.10
## [76] R6_2.5.1                rprojroot_2.0.3         evaluate_0.20          
## [79] lattice_0.21-8          highr_0.10              R.methodsS3_1.8.2      
## [82] png_0.1-8               paws.common_0.5.6       bslib_0.4.2            
## [85] Rcpp_1.0.10             xfun_0.39               pkgconfig_2.0.3

The `SpatialData` class

April 30, 2023

Abstract

Package

Contents

1 Preamble

1.1 Dependencies

1.2 Introduction

2 `SpatialData`

2.1 Accession

3 `ZarrArray`

4 Transformations

4.1 scale

4.2 rotate

5 Visualization

6 Query

7 Appendix

7.1 Session info

The SpatialData class

April 30, 2023

Abstract

Package

Contents

1 Preamble

1.1 Dependencies

1.2 Introduction

2 SpatialData

2.1 Accession

3 ZarrArray

4 Transformations

4.1 scale

4.2 rotate

5 Visualization

6 Query

7 Appendix

7.1 Session info

The `SpatialData` class

2 `SpatialData`

3 `ZarrArray`